导航菜单

  • 1.概述
  • 2.功能与能力
  • 3.系统架构
  • 4.部署与配置
  • 5.Docker 部署
  • 6.环境配置
  • 7.外部服务设置
  • 8.AI模型与LLM配置
  • 9.核心系统
  • 10.文档处理流水线
  • 11.RAG引擎与搜索
  • 12.知识库管理系统
  • 13.对话与对话系统
  • 14.翻译与跨语言支持
  • 15.用户界面
  • 16.主应用界面
  • 17.管理仪表盘
  • 18.文档编写界面
  • 19.知识库内容管理
  • 20.国际化与本地化
  • 21.管理功能
  • 22.用户与团队管理
  • 23.文件和存储管理
  • 24.知识库管理
  • 25.系统监控与健康状态
  • 26.API 参考
  • 27.知识库API
  • 28.对话与聊天API
  • 29.文件管理API
  • 30.管理与Admin API
  • 31.开发指南
  • 32.前端开发
  • 33.后端服务架构
  • 34.数据库模式与模型
  • 35.基础设施与文档
  • 36.快速入门指南
  • 1. 目的与范围
  • 2. API架构概述
    • 2.1 API系统架构
    • 2.2 请求/响应流程
  • 3. 知识库管理API
    • 3.1 核心知识库端点
    • 3.2 知识库服务架构
    • 3.3 创建知识库请求
    • 3.4 嵌入模型配置
  • 4. 文档管理API
    • 4.1 文档处理流水线
    • 4.2 文档解析流程
    • 4.3 批量处理API
  • 5. 对话与聊天API
    • 5.1 核心对话端点
    • 5.2 聊天请求格式
    • 5.3 流式响应
  • 6. 文件管理API
    • 6.1 文件上传端点
    • 6.2 文件管理端点
  • 7. 管理与Admin API
    • 7.1 用户管理端点
    • 7.2 团队管理端点
    • 7.3 系统配置端点
  • 8. 认证与授权
    • 8.1 认证方式
    • 8.2 权限控制
  • 9. 错误处理
    • 9.1 错误响应格式
    • 9.2 常见错误码
  • 10. 速率限制
  • 11. 最佳实践
    • 11.1 请求优化
    • 11.2 错误处理
    • 11.3 性能优化
  • 12. 总结

# API 参考

1. 目的与范围 #

本文档提供Ragflow-Plus中所有REST API端点和服务的完整文档，涵盖HTTP API接口、请求/响应格式、服务层架构以及知识库管理、文档处理、对话AI和管理功能的集成模式。

关于使用这些API的前端UI组件，请参阅 用户界面。关于底层RAG引擎和搜索能力，请参阅 RAG引擎与搜索。

2. API架构概述 #

Ragflow-Plus通过两个主要系统暴露API：核心应用API服务器和管理系统API服务器。核心系统处理面向用户的聊天和检索操作，而管理系统提供知识库和文档管理的管理界面。

2.1 API系统架构 #

系统采用分层架构，从前端应用到数据层：

graph TB subgraph Frontend Applications UserApp[User Application
web/src/] MgmtApp[Management Application
management/web/src/] end subgraph API Gateway Layer CoreAPI[Core API Server
api/] MgmtAPI[Management API Server
management/server/] end subgraph Service Layer DialogService[DialogService
dialog_service.py] KBService[KnowledgebaseService
service.py] DocumentParser[DocumentParser
document_parser.py] FileService[File Management] end subgraph Data Layer MySQL[MySQL Database] ES[Elasticsearch] MinIO[MinIO Storage] Redis[Redis Cache] end UserApp --> CoreAPI MgmtApp --> MgmtAPI CoreAPI --> DialogService MgmtAPI --> KBService MgmtAPI --> DocumentParser DialogService --> MySQL DialogService --> ES KBService --> MySQL KBService --> MinIO DocumentParser --> ES DocumentParser --> MinIO

2.2 请求/响应流程 #

典型的API请求流程：

sequenceDiagram participant Client participant "API Route" participant "Service Layer" participant "Database" participant "External Service" Client->>"API Route": HTTP Request "API Route"->>"Service Layer": Call service method "Service Layer"->>"Database": Query/Update data "Database"-->>"Service Layer": Return data "Service Layer"->>"External Service": AI/Embedding call "External Service"-->>"Service Layer": Return result "Service Layer"-->>"API Route": Return processed data "API Route"-->>Client: JSON Response

3. 知识库管理API #

知识库管理API提供用于创建、更新和管理知识库及其关联文档的端点。

3.1 核心知识库端点 #

方法 端点 描述
GET /api/v1/knowledgebases 列出知识库（支持分页和过滤）
POST /api/v1/knowledgebases 创建新知识库
GET /api/v1/knowledgebases/{kb_id} 获取知识库详情
PUT /api/v1/knowledgebases/{kb_id} 更新知识库元数据
DELETE /api/v1/knowledgebases/{kb_id} 删除知识库
DELETE /api/v1/knowledgebases/batch 批量删除知识库

3.2 知识库服务架构 #

知识库服务采用分层架构：

graph TB subgraph API Routes KBRoutes[knowledgebases/routes.py] end subgraph Service Layer KBService[KnowledgebaseService] CreateKB[create_knowledgebase()] UpdateKB[update_knowledgebase()] DeleteKB[delete_knowledgebase()] GetKBList[get_knowledgebase_list()] end subgraph Database Operations MySQL_KB[knowledgebase table] MySQL_User[user table] MySQL_TenantLLM[tenant_llm table] end KBRoutes --> KBService KBService --> CreateKB KBService --> UpdateKB KBService --> DeleteKB KBService --> GetKBList CreateKB --> MySQL_KB CreateKB --> MySQL_User CreateKB --> MySQL_TenantLLM UpdateKB --> MySQL_KB DeleteKB --> MySQL_KB GetKBList --> MySQL_KB GetKBList --> MySQL_User

3.3 创建知识库请求 #

创建知识库的请求格式：

{
  "name": "My Knowledge Base",
  "description": "Knowledge base description",
  "language": "Chinese",
  "permission": "me",
  "creator_id": "user_uuid",
  "embd_id": "bge-m3"
}

create_knowledgebase方法在management/server/services/knowledgebases/service.py中处理知识库创建，包括自动嵌入模型选择和租户管理。

3.4 嵌入模型配置 #

嵌入模型配置相关端点：

方法 端点 描述
GET /api/v1/knowledgebases/system_embedding_config 获取系统嵌入配置
POST /api/v1/knowledgebases/system_embedding_config 设置系统嵌入配置
GET /api/v1/knowledgebases/embedding_config?kb_id={id} 获取知识库嵌入配置
GET /api/v1/knowledgebases/embedding_models/{kb_id} 获取可用嵌入模型

4. 文档管理API #

文档管理API处理知识库内的文档上传、解析和生命周期管理。

4.1 文档处理流水线 #

文档处理流水线架构：

graph TB subgraph Document API Endpoints AddDoc[POST /knowledgebases/{kb_id}/documents] ParseDoc[POST /documents/{doc_id}/parse] GetProgress[GET /documents/{doc_id}/parse/progress] DeleteDoc[DELETE /documents/{doc_id}] end subgraph Document Processing DocumentParser[DocumentParser] MinerU[MinerU Parser] ChunkGeneration[Chunk Generation] EmbeddingGen[Embedding Generation] end subgraph Storage Systems FileTable[file table] DocumentTable[document table] File2Doc[file2document table] ES_Storage[Elasticsearch] MinIO_Storage[MinIO] end AddDoc --> DocumentTable AddDoc --> File2Doc ParseDoc --> DocumentParser DocumentParser --> MinerU MinerU --> ChunkGeneration ChunkGeneration --> EmbeddingGen EmbeddingGen --> ES_Storage EmbeddingGen --> MinIO_Storage GetProgress --> DocumentTable DeleteDoc --> DocumentTable DeleteDoc --> ES_Storage

4.2 文档解析流程 #

文档解析过程由management/server/services/knowledgebases/document_parser.py中的perform_parse函数处理。解析支持多种文件类型：

  • PDF文档：使用MinerU，支持OCR和文本提取模式
  • Office文档：Word、PowerPoint、Excel文件通过MinerU处理
  • 文本文件：Markdown、HTML、纯文本
  • 图像：支持OCR处理的视觉内容

4.3 批量处理API #

批量处理相关端点：

方法 端点 描述
POST /api/v1/knowledgebases/{kb_id}/documents/batch 批量上传文档
POST /api/v1/documents/batch/parse 批量解析文档
GET /api/v1/documents/batch/progress 获取批量处理进度

5. 对话与聊天API #

对话和聊天API提供RAG增强的对话功能。

5.1 核心对话端点 #

方法 端点 描述
POST /api/v1/chat 发送聊天消息（流式响应）
GET /api/v1/dialogs 获取对话列表
GET /api/v1/dialogs/{dialog_id} 获取对话详情
DELETE /api/v1/dialogs/{dialog_id} 删除对话
POST /api/v1/dialogs/{dialog_id}/messages 添加消息到对话

5.2 聊天请求格式 #

聊天请求示例：

{
  "question": "用户问题",
  "kb_ids": ["kb_uuid_1", "kb_uuid_2"],
  "dialog_id": "dialog_uuid",
  "stream": true,
  "rerank": true,
  "top_n": 5
}

5.3 流式响应 #

聊天API支持Server-Sent Events (SSE)流式响应，实时返回AI生成的文本片段。

6. 文件管理API #

文件管理API处理文件上传、下载和存储管理。

6.1 文件上传端点 #

方法 端点 描述
POST /api/v1/files/upload 单文件上传
POST /api/v1/files/upload/batch 批量文件上传
POST /api/v1/files/upload/chunk 分块文件上传（初始化）
POST /api/v1/files/upload/chunk/{upload_id} 分块文件上传（上传块）
POST /api/v1/files/upload/chunk/{upload_id}/complete 分块文件上传（完成）

6.2 文件管理端点 #

方法 端点 描述
GET /api/v1/files 获取文件列表
GET /api/v1/files/{file_id} 获取文件详情
GET /api/v1/files/{file_id}/download 下载文件
DELETE /api/v1/files/{file_id} 删除文件

7. 管理与Admin API #

管理和Admin API提供系统管理功能。

7.1 用户管理端点 #

方法 端点 描述
GET /api/v1/admin/users 获取用户列表
POST /api/v1/admin/users 创建用户
PUT /api/v1/admin/users/{user_id} 更新用户
DELETE /api/v1/admin/users/{user_id} 删除用户

7.2 团队管理端点 #

方法 端点 描述
GET /api/v1/admin/teams 获取团队列表
POST /api/v1/admin/teams 创建团队
PUT /api/v1/admin/teams/{team_id} 更新团队
DELETE /api/v1/admin/teams/{team_id} 删除团队

7.3 系统配置端点 #

方法 端点 描述
GET /api/v1/admin/system/status 获取系统状态
GET /api/v1/admin/system/version 获取系统版本
POST /api/v1/admin/system/config 更新系统配置

8. 认证与授权 #

8.1 认证方式 #

API支持以下认证方式：

  • API Token：在请求头中传递Authorization: Bearer {token}
  • Session Cookie：基于会话的认证（用于Web界面）

8.2 权限控制 #

  • 用户级别：用户可以访问自己的资源
  • 团队级别：团队成员可以访问团队共享资源
  • 管理员级别：管理员可以访问所有资源

9. 错误处理 #

9.1 错误响应格式 #

标准错误响应格式：

{
  "code": 400,
  "message": "错误描述",
  "data": null,
  "error": "详细错误信息"
}

9.2 常见错误码 #

  • 200：成功
  • 400：请求错误
  • 401：未授权
  • 403：禁止访问
  • 404：资源不存在
  • 500：服务器错误

10. 速率限制 #

API请求受到速率限制：

  • 普通用户：每分钟100次请求
  • 管理员：每分钟500次请求
  • 批量操作：每个操作限制为10个并发请求

11. 最佳实践 #

11.1 请求优化 #

  • 使用分页参数减少响应大小
  • 使用过滤参数精确查询
  • 批量操作时使用批量端点

11.2 错误处理 #

  • 始终检查响应状态码
  • 实现重试机制处理临时错误
  • 记录错误信息用于调试

11.3 性能优化 #

  • 使用流式响应处理长文本生成
  • 缓存频繁访问的数据
  • 使用异步请求处理批量操作

12. 总结 #

本文档提供了Ragflow-Plus API的完整参考。更多详细信息，请参阅：

  • 知识库API
  • 对话与聊天API
  • 文件管理API
  • 管理与Admin API

访问验证

请输入访问令牌

Token不正确，请重新输入